Skip to main content

​
Authentication Modes

Mission Control supports two authentication modes:

Local Token

Single shared bearer token for self-hosted deployments

Clerk JWT

Multi-user JWT authentication via Clerk

​
Configuration

The authentication mode is configured via the AUTH_MODE environment variable: 
AUTH_MODE=local  # or "clerk"

​
User Authentication

​
Local Mode

In local mode, all requests use a single shared bearer token: 
curl -H "Authorization: Bearer YOUR_LOCAL_AUTH_TOKEN" \
  https://api.example.com/api/v1/users/me
Requirements:
  • Token must be at least 50 characters
  • Token is stored in LOCAL_AUTH_TOKEN environment variable
  • All authenticated users map to a single admin@home.local account

​
Clerk Mode

In Clerk mode, each user authenticates with a Clerk-issued JWT: 
curl -H "Authorization: Bearer CLERK_SESSION_TOKEN" \
  https://api.example.com/api/v1/users/me
Token Validation:
  • JWT signature is verified using Clerk’s public keys
  • User identity is extracted from the sub claim
  • Email and name are extracted from token claims or fetched from Clerk API
  • User records are automatically created/synced on first authentication

​
Agent Authentication

Agents authenticate using a separate token system. See Agent Tokens for details.

​
Authentication Flow

1

Client obtains token

  • Local mode: Token is configured in environment variables
  • Clerk mode: User signs in via Clerk UI to obtain JWT
2

Client includes token in request

Add Authorization: Bearer <token> header to all API requests
3

Backend validates token

  • Local mode: Constant-time comparison against LOCAL_AUTH_TOKEN
  • Clerk mode: JWT signature verification with clock skew tolerance
4

User context is resolved

  • Local mode: Returns or creates the local admin user
  • Clerk mode: Creates/updates user record from token claims

​
Bootstrap Endpoint

Use the bootstrap endpoint to resolve your authenticated identity: 
curl -X POST https://api.example.com/api/v1/auth/bootstrap \
  -H "Authorization: Bearer YOUR_TOKEN"
Response: 
{
  "id": "11111111-1111-1111-1111-111111111111",
  "clerk_user_id": "user_2abcXYZ",
  "email": "alex@example.com",
  "name": "Alex Chen",
  "preferred_name": "Alex",
  "pronouns": "they/them",
  "timezone": "America/Los_Angeles",
  "notes": "Primary operator for board triage.",
  "context": "Handles incident coordination and escalation.",
  "is_super_admin": false
}

​
Error Responses

​
401 Unauthorized

Returned when authentication fails: 
{
  "detail": {
    "code": "unauthorized",
    "message": "Not authenticated"
  },
  "code": "unauthorized",
  "retryable": false
}
Common causes:
  • Missing Authorization header
  • Invalid token format
  • Expired JWT (Clerk mode)
  • Token mismatch (Local mode)

​
Security Considerations

Local Mode Security: Local mode uses a single shared token. Only use this mode for:
  • Self-hosted deployments with trusted network access
  • Development and testing environments
  • Single-user or single-team deployments
For multi-user production deployments, use Clerk mode.
Token Storage: Never commit tokens to version control. Use environment variables or secure secret management systems.

​
Next Steps

Local Token Setup

Configure local token authentication

Clerk Integration

Set up Clerk JWT authentication

Agent Tokens

Authenticate agent API clients

API Reference

View authentication endpoints